 (September 1999)(Disk 2).iso/Technical Publications/quicktime/qtdevdocs/images/qtsmban.gif){kind=small}
 (September 1999)(Disk 2).iso/Technical Publications/quicktime/qtdevdocs/images/qt4api.gif)
Inside Macintosh: QuickTime Components
The Movie Toolbox provides a number of support functions for clock components. All of these functions help your component manage its associated callback functions. Your clock component may call any of these functions at interrupt time. These functions should only be called by clock components.
Use the AddCallBackToTimeBase function to add a callback event to the list of scheduled callback events maintained by the Movie Toolbox. You should use the RemoveCallBackFromTimeBase function to remove a callback event from the list.
When your clock component determines that it is time to invoke a callback function, you should use the ExecuteCallBack function to cause the Movie Toolbox to call the function.
If your clock component needs to scan all its associated callback events, you can use the GetFirstCallBack and GetNextCallBack functions.
Your clock component uses the AddCallBackToTimeBase function to place a callback event into the list of scheduled callback events. The Movie Toolbox maintains this list.
pascal OSErr AddCallBackToTimeBase (QTCallBack cb);
Your component should call the AddCallBackToTimeBase function when your ClockCallMeWhen function determines that your component can support the callback event (see "Using the Callback Functions," which begins on Using the Callback Functions , for more information about the ClockCallMeWhen function).
If your component does not call this function, the Movie Toolbox does not notify your component of time, rate, or stop and start changes (via the ClockRateChanged and ClockTimeChanged functions, described on ClockRateChanged and ClockTimeChanged , respectively).
When your clock component determines that it is time to execute a callback function, your component should call the ExecuteCallBack function.
pascal void ExecuteCallBack (QTCallBack cb);
This function handles all the details of invoking the callback function properly. For example, the ExecuteCallBack function queues the callback function correctly, according to the function's ability to execute at interrupt time (specified in the callBackType parameter to your ClockNewCallBack function, described on ClockNewCallBack ).
Before calling the application's function, the ExecuteCallBack function cancels the callback event. In this manner, the callback event is prevented from executing twice in succession. It is up to the application, or the callback function itself, to reschedule the callback event.
This function sets the A5 register to the value it contained at the time the callback event was scheduled when calling the callback function.
Your clock component should not release the memory associated with the callback event at this time. You should do so only in your ClockDisposeCallBack function (described on ClockDisposeCallBack ). This is particularly important when a callback function cannot execute at interrupt time, since the Movie Toolbox schedules such functions for invocation at a later time.
Your clock component uses the RemoveCallBackFromTimeBase function to remove a callback event from the list of scheduled callback events. The Movie Toolbox maintains this list.
pascal OSErr RemoveCallBackFromTimeBase (QTCallBack cb);
Your component should call the RemoveCallBackToTimeBase function when your ClockCancelCallBack function determines that your component can cancel the callback event (see "Using the Callback Functions," for more information about the ClockCancelCallBack function).
Your component should call the RemoveCallbackFromTimeBase function only for callback events that were successfully added to the schedule with the AddCallBackToTimeBase function (described on AddCallBackToTimeBase ).
The GetFirstCallBack function returns the first callback event associated with a specified time base. Your component can use this function, along with the GetNextCallBack function (described in the next section), to scan all callback events associated with a time base.
pascal QTCallBack GetFirstCallBack (TimeBase tb);
The GetFirstCallBack function returns the first callback event in the list managed for the specified time base. If there are no callback events associated with the time base, the QTCallBack result is set to nil . Your component cannot assume that the Movie Toolbox maintains the callback list in any particular order.
The GetNextCallBack function returns the next callback event associated with a specified time base. Your component can use this function, along with the GetFirstCallBack function (described in the previous section), to scan all callback events associated with a time base.
pascal QTCallBack GetNextCallBack (QTCallBack cb);
The GetNextCallBack function returns the next callback event in the list managed for the specified time base. If there are no more callback events associated with the time base, the returned QuickTime callback header structure is set to nil . Your component cannot assume that the Movie Toolbox maintains the callback list in any particular order .